       Tool 219 ($DB)  (SoundTrack Player or ST). 



STStartup        ($02DB)

Parameters:
					previous contents
	  Stack before call:	MemId: Word

	  Stack after call  :	previous contents

Errors:	$DB01		ST already started up

STStartup initializes the ST. This call installs a sound interrupt driven task (using oscillator #30) that allows to change the music tempo and handle the sound effects. Therefore, you should startup this tool just before playing a music and shut it down when it is finished if speed is critical for your application. ST is not compatible with other sequencer tools like SynthLab because it uses all the available oscillators.


STShutDown.      ($03DB)

Parameters: The stack is not affected by this call. There are no input or 		  output parameters.

Errors:	  None

STShutdown stops the music, frees the memory allocated for the musics and stops the sound interrupts.


STVersion.     ($04DB)

Parameters:
					
	  Stack before call:	previous contents

					previous contents
	  Stack after call  :	VersionInfo: Word

Errors:	None

Returns the version number of the SoundTrack player.
Example  $0100 = 1.0.


STStatus.        ($06DB)

	  Stack before call:	previous contents

					previous contents
	  Stack after call  :	Status: Word (Boolean; True if active)

Errors:	None

Indicates whether the SoundTrack player is active.
Returns True ($0001) if active or ($0000) else.


STLoadOneMusic.  ($09DB)

Parameters:
					previous contents
	  Stack before call:	Filename: Pointer

	  Stack after call  :	previous contents

Errors:	$DB02		ST not started up
		$DB04		Not a SoundSmith music.

Loads the music and it's wavebank. The wavebank must be created using the Save Sound file option (don't forget to set the file format to GS SoundSmith in the preferences dialog box) and must have the same name as the music and end with .W.

Example: 	Music name= 	Alf
		Wavebank name=	Alf.W 

Once the music is loaded, the wavebank is copied into the DOC ram and the memory it was using is freed. You should use this call when you just need to play a single music. Otherwise use the Batch call.
STPlayMusic.     ($0ADB)
	
Parameters:
					previous contents
	  Stack before call:	LoopMode: Boolean

	  Stack after call  :	previous contents

Errors:	$DB02		ST not started up
		$DB03		There is no initialized music.

Plays the last selected music which is the last music loaded by LoadOneMusic or the one selected by SelectBatchMusic. LoopMode indicates if the music player should restart the music when it is finished ($0001 = True) or not ($0000 = False).

Example: load and play a music that loops.

In assembly language:

		pea   ^FileName
		pea   FileName
		ldx   #$09DB
		jsl   $E10000      ; _STLoadOneMusic
	     	_Err

		pea   $0001
		ldx   #$0ADB
		jsl   $E10000      ; _STPlayMusic
		_Err
     	...

FileName 	str   '1/MusicFile'

In Pascal :

		STLoadOneMusic('1/MusicFile');
		STPlayMusic(True);


STStopMusic.     ($0BDB)

Parameters: The stack is not affected by this call. There are no input or 		  output parameters.

Errors:	  None

Stops the music.


STGetEndOfMusic. ($0CDB)

	  Stack before call:	previous contents

					previous contents
	  Stack after call  :	FinishedFlag: Word (Boolean; True if ended)

Errors:	  None

Returns True ($0001) if music ended (even if it loops).


STAddToBatch.    ($0DDB)

Parameters:
					previous contents
					Filename: Pointer
	  Stack before call:	BatchNb:  Integer

	  Stack after call  :	previous contents

Errors:	$DB02		ST not started up
		$DB05		There is already a music in BatchNb
		$DB06		Illegal BatchNb

Loads a music and it's wavebank in memory and gives it a reference number which must between 1 and 25. Unlike with LoadOneTool, you will have to select a music using STSelectBatch to play it.





STSelectBatch.   ($0EDB)

Parameters:
					previous contents
	  Stack before call:	BatchNb:  Integer

	  Stack after call  :	previous contents

Errors:	$DB06		Illegal BatchNb
		$DB07		There is no music with BatchNb

Selects the next music to play. STSelectBatch stops the music if there is one playing and frees the memory allocated by LoadOneMusic if you used that call to play the music (however you should not mix calls to STLoadOneMusic and STAddToBatch).

Example : Load and play two musics.

In assembly language:

 		pea   ^FileName1
		pea   FileName1
		pea   #1           		; Music #1
		ldx   #$0CDB
		jsl   $E10000		; _STAddToBatch
		_Err

 		pea   ^FileName2
		pea   FileName2
		pea   #2           		; Music #2
		ldx   #$0CDB
		jsl   $E10000		; _STAddToBatch
	    	_Err

		pea   #1
		ldx   #$0DDB		; _STSelectBatch
		jsl   $E10000
		_Err

		pea   #0			; False
		ldx   #$0ADB		; _STPlayMusic
		jsl   $E10000
		_Err				; Play music #1

]lp		pea   #0
		ldx   #$0CDB
		jsl   $E10000
		pla
		beq   ]lp			; loop until the music ends.

		pea   #2			; select music #2
		ldx   #$0DDB		; _STSelectBatch
		jsl   $E10000
		_Err

		pea   #0			; False
		ldx   #$0ADB		; _STPlayMusic
		jsl   $E10000
		_Err				; Play music #2

FileName1 str   '1/Music1'
Filename2 str   '1/Music2'

En Pascal :

		STAddToBatch('1/Music1',1);
		STAddToBatch('1/Music2',2);
		STSelectBatch(1);
		STPlayMusic(False);
		 While not STGetEndOfMusic;
		STSelectBatch(2);
		STPlayMusic(False);











STKillBatch.     ($0FDB)

Parameters:
					previous contents
	  Stack before call:	BatchNb:  Integer

	  Stack after call  :	previous contents

Errors:	$DB02		ST not started up
		$DB06		Illegal BatchNb
		$DB07		There is no music with BatchNb

Frees the memory allocated for the music BatchNb and removes it from the  music list. If that music was playing, it stops it. If you set BatchNb to 0, all the musics are removed.


STGetPlayingMusic. ($10DB)

	  Stack before call:	previous contents

					previous contents
	  Stack after call  :	MusicNb: Word

Errors:	None

Returns -1 ($FFFF) if no music is playing, 0 if the music was loaded using LoadOneMusic or otherwise it's BatchNum.


STPlayBatch.     ($11DB)

Parameters:
					previous contents
	  Stack before call:	List:  Pointer

	  Stack after call  :	previous contents

Errors:	$DB02		ST not started up
		$DB08		Illegal sequence

Allows to play a sequence of musics. Therefore you need to define a list of words (Integers) that contains the numbers of the musics to play. A list must end with a 0 ( End ) or -1 ($FFFF if you want the sequence to loop). 

Example : Play musics 1 and 2, repeat music 2, continue playing music 3, and start over.

In assembly language :

     	  pea    ^BatchList
            pea    BatchList
            ldx    #$11DB
            jsl    $E10000
            _Err

BatchList   da     1,2,2,3,$FFFF

In Pascal, you must use a pointer to an Array of Integer. But you don't need to care about that since the TPtrTListe type has already be defined.

	Program Soundtrack;

	Use ST;

	Var Liste : TPtrTListe;

	Begin
	   STStartup(Id);
	   New(Liste);      
	   ...
	   STAddToBatch('1/Music1',1);
	   STAddToBatch('1/Music2',2);
	   STAddToBatch('1/Music3',3);
	   Liste^[1]:= 1; Liste^[2]:=2; Liste^[3]:=2; Liste^[4]:=3;
	   Liste^[5]:=-1;
	   STPlayBatch(Liste);
	   ...
	   STShutDown;
	End.


STGetTrackVu.    ($12DB)

	  Stack before call:	previous contents

					previous contents
	  Stack after call  :	VuMetre Table Address: Pointer

Errors:	None

Returns the address in RAM of table containing 16bits pseudo-volumes (values contained between $0000 and $00FF) for each of the used tracks and instruments. The $20 first values correspond to the volume of the 14 tracks (there are four unused bytes) and the $20 next ones to the volume of each instrument. 
The volume values are updated each time a new note is played. The table allows to draw on the screen  VuMetres that show the volumes of the instruments or the tracks volume.
See the demo program for more information.


STPauseMusic.    ($13DB)

Parameters: The stack is not affected by this call. There are no input or 		  output parameters.

Errors:	  None

Even if you don't believe it, this call stops the music... You can resume it by using STContinueMusic.


STContinueMusic. ($14DB)

Parameters: The stack is not affected by this call. There are no input or 		  output parameters.

Errors:	  None

Resumes a music where it had been paused using STPauseMusic.


